/*
 * Copyright 2010 Assert Developments
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * 	http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package be.ad.coffeebreak.services;

import be.ad.coffeebreak.domain.User;

import java.util.List;

/**
 * An interface for user services.
 *
 * @author Stefan Bangels
 */
public interface UsersService {

    /**
     * Find all users.
     *
     * @return a list of users
     */
    public List<User> findAllUsers();

    /**
     * Find a user by id.
     *
     * @param userId the user id
     * @return the user or null when the user is not found
     */
    public User findUserById(long userId);

    /**
     * Find a user by email address.
     *
     * @param email the email address
     * @return the user or null when the user is not found
     * @throws IllegalArgumentException when email is null
     */
    public User findUserByEmail(String email);

    /**
     * Create or update a user.
     * <p/>
     * If the user has an id, the user is updated. When the user hasn't got an id, a new user is inserted.
     * The user email has to be unique, otherwise an SQL exception is thrown.
     * <p/>
     * When inserting a user:
     * User email, name, country, language, timezone are updated.
     * A new user id is generated.
     * <p/>
     * When updating a user:
     * User name, country, language, timezone are updated.
     * User id and email remain the same.
     *
     * @param user the user
     * @return the created/updated user
     * @throws IllegalArgumentException when inserting and user, user#email, user#name is null
     *                                  or when updating and when user, user#name is null
     */
    public User saveUser(User user);

    /**
     * Delete a user by id.
     * <p/>
     * This method is idempotent: when the user does not exist, no exception is thrown but a warning is logged.
     *
     * @param userId the user id
     */
    public void deleteUser(long userId);

}
